Segment

Send events to the Algolia Insights API with Segment.

If you’re using Twilio Segment to track user interactions on your website or app, you can set up Algolia as a destination to forward click and conversion events.

Live demo

CodeSandbox

Source code

GitHub

Integrating Algolia with Segment has three steps:

1. Enable the Algolia destination in Segment.
2. Enable clickAnalytics with your searches.
3. Augment your Segment events with Algolia-related data.

Enable the Algolia destination in Segment

To add the Algolia destination to Segment, follow these steps:

1. Sign into Segment app

   Sign in to your Segment web app and select the workspace you want to work in.

2. Select source

   Select the source you want to set up and click Add Destination.

   

3. Select destination

   Search for the Algolia destination and select it to add it.

   

   Segment docs

   Sending Segment data to destinations

   Segment docs

   Algolia Insights destination

4. Sign into Algolia

   Sign in to your Algolia account and select the application you want to configure.

5. Add your credentials

   Copy your application ID and search API key from the dashboard and paste it into Segment.

   

Enable clickAnalytics

To relate click and conversion events to searches, Algolia needs a query ID. To get the queryID parameter for a search, set the clickAnalytics parameter to true:

Vanilla JavaScript

index.search('YourSearchQuery', {
    userToken: 'user-1',
    clickAnalytics: true
}).then(({ hits, queryID }) => {
    console.log(hits, queryID);
})

Identify users

If you use Segment’s analytics.identify() function to identify users, use the same identifier for Algolia by passing it as the userToken parameter with your search. For example, if you want to use Personalization:

Vanulla JavaScript

index.search('YourSearchQuery', {
    userToken: 'user-1',
    enablePersonalization: true
}).then(({ hits }) => {
    console.log(hits);
})

Augment your Segment events with Algolia-related data

Algolia requires these properties that aren’t part of the regular Segment specifications:

Property	Type	Required?
index	string	Yes
eventType	value: 'view', 'click', or 'conversion'	Yes
eventSubtype	value: 'addToCart' or 'purchase' (only applicable to 'conversion' events)	No
queryID	string	No
objectIDs	string[] or objectID: string	No
positions	number[] or position: number	No
filters	Array<{ type: string; value: string; }> or string[] (${type}:${value}—for example, brand:apple)	No
objectData	See the Insights API reference for the objectData parameter (only applicable to 'addToCart' and 'purchase' events)	No

For more information, see the Insights API reference.

You can get these properties with the following code:

Vanilla JavaScript

index.search('query', {
    userToken: 'user-1',
}).then(({ hits, queryID, hitsPerPage, page }) => {
    hits.map((hit, index) => {
    const position = index + 1 + page * hitsPerPage;
    const objectID = hit.objectID;
    });
});

The following code is an example of a click event tracked with Segment that includes all the necessary Algolia-related properties:

JavaScript

analytics.track('Product Clicked', {
  product_id: '507f1f77bcf86cd799439011',
  sku: 'G-32',
  category: 'Games',
  name: 'Monopoly: 3rd Edition',
  brand: 'Hasbro',
  variant: '200 pieces',
  price: 18.99,
  quantity: 1,
  coupon: 'MAYDEALS',
  position: 3,
  url: 'https://www.example.com/product/path',
  image_url: 'https://www.example.com/product/path.jpg',
  // Algolia-related properties
+ index: 'my-algolia-index',
+ eventType: 'click',
+ queryID: 'fd0bbaadc287937s7671d00f1d053b88',
+ objectID: '131280270'
});

Refer to Segment’s Algolia Insights destination documentation for details on which Segment events are supported by default.

Debug events with Segment

If you have administrator permissions for your Segment source, you can send test events. To do this, select your source and click Validate. Select Algolia Insights as the destination.

Now, you can send a test event using the Event builder or JSON editor.

A green box with the status “200 OK” means that Segment successfully sent a test event to the Algolia Insights destination. To check, if the event delivery was successful, go to the Event Delivery tab.

For example, sending an event with a wrong queryID shows a Delivery Issue.

To check if Algolia receives your events correctly, go to the Events Debugger in the Algolia dashboard. For more information, see Validate your events.